OFIQ C# Wrapper Library Requirements
Project Overview
Create a .NET 8 wrapper library for the Open Source Face Image Quality (OFIQ) C++ library, providing a modern, type-safe, and performant C# API for facial image quality assessment.
Target Framework
- .NET 8.0 (Long Term Support)
- Multi-platform: win-x64, linux-x64, linux-arm64, osx-x64, osx-arm64
- Language: C# 12 with modern features
Core Requirements
1. Native Interoperability
- Use P/Invoke to interface with OFIQ native library (
libofiq_lib.so/libofiq_lib.dylib/ofiq_lib.dll)
- Handle memory management and resource cleanup
- Provide safe abstractions over unsafe native calls
- Support both Release and Debug builds of native library
2. API Design
- Main Entry Point:
OFIQEngine class implementing IDisposable
- Configuration:
OFIQConfiguration for JAXN configuration management
- Results:
FaceImageQualityAssessment with typed results
- Quality Measures: Enumeration of all 28 ISO/IEC 29794-5 measures
- Error Handling: Structured exception hierarchy
3. Data Structures
Image - Support multiple image formats (PNG, JPEG, BMP)
LandmarkPoint and Landmarks - Facial landmark data
QualityMeasureResult - Native score and quality value
FaceImageQualityAssessment - Complete assessment results
PreprocessingResults - Access to intermediate processing data
4. Quality Measures Support
Wrap all 28 quality measures defined in ISO/IEC 29794-5:
- 0x41: UnifiedQualityScore
- 0x42: BackgroundUniformity
- 0x43: IlluminationUniformity
- 0x44-0x45: Luminance (mean and variance)
- 0x46: UnderExposurePrevention
- 0x47: OverExposurePrevention
- 0x48: DynamicRange
- 0x49: Sharpness
- 0x4A: NoCompressionArtifacts
- 0x4B: NaturalColour
- 0x4C: SingleFacePresent
- 0x4D: EyesOpen
- 0x4E: MouthClosed
- 0x4F: EyesVisible
- 0x50: MouthOcclusionPrevention
- 0x51: FaceOcclusionPrevention
- 0x52: InterEyeDistance
- 0x53: HeadSize
- 0x54-0x57: CropOfTheFaceImage (left, right, above, below)
- 0x58-0x5A: HeadPose (yaw, pitch, roll)
- 0x5B: ExpressionNeutrality
- 0x5C: NoHeadCoverings
5. Configuration System
- Load JAXN configuration files
- Support relative and absolute model paths
- Quality mapping configuration via sigmoid functions
- Default configuration fallback
6. Image Processing
- Support common image formats via System.Drawing.Common
- Memory-efficient image loading
- Cross-platform image format support
- EXIF metadata handling
- Minimal overhead over native calls
- Efficient memory usage for image processing
- Thread-safe operations where applicable
- Support for batch processing
8. Error Handling
- Structured exception types (
OFIQException, ConfigurationException, ImageLoadException)
- Native error code mapping to .NET exceptions
- Resource cleanup on errors
Technical Implementation
Project Structure
OFIQ-CSharp-Wrapper/
├── src/
│ ├── OFIQ.Native/
│ │ ├── Interop/ - P/Invoke declarations
│ │ ├── SafeHandles/ - SafeHandle implementations
│ │ └── OFIQ.Native.csproj
│ ├── OFIQ.Core/
│ │ ├── Types/ - Data structures
│ │ ├── Configuration/ - Configuration system
│ │ ├── QualityMeasures/ - Quality measure definitions
│ │ └── OFIQ.Core.csproj
│ ├── OFIQ/
│ │ ├── OFIQEngine.cs - Main API
│ │ ├── Extensions/ - Helper methods
│ │ └── OFIQ.csproj
│ └── OFIQ.Extensions/
│ ├── DependencyInjection/ - DI integration
│ └── OFIQ.Extensions.csproj
├── tests/
│ ├── OFIQ.Tests.Unit/
│ ├── OFIQ.Tests.Integration/
│ └── OFIQ.Benchmarks/
├── samples/
│ ├── ConsoleApp/
│ ├── WebApi/
│ └── BlazorApp/
└── docs/
Dependencies
- System.Drawing.Common - Cross-platform image processing
- System.Text.Json - Configuration serialization
- Microsoft.Extensions.DependencyInjection - Optional DI support
- xUnit - Testing framework
- BenchmarkDotNet - Performance testing
Build and Deployment
- Multi-target for all supported platforms
- Native library bundling strategy
- NuGet package creation
- Native AOT compilation support
- CI/CD pipeline configuration
Testing Requirements
Unit Tests
- All public API methods
- Configuration loading and validation
- Error condition handling
- Memory management verification
Integration Tests
- End-to-end quality assessment
- Cross-platform compatibility
- Performance benchmarks
- Memory leak detection
Sample Applications
- Console application for command-line usage
- Web API for RESTful interface
- Blazor application for web interface
- Performance benchmarking tool
Documentation
- XML documentation for all public APIs
- README with quick start guide
- API reference documentation
- Sample code and tutorials
- Performance guidelines
Compliance
- MIT license compatibility
- Proper attribution of OFIQ dependencies
- Cross-platform compatibility testing
- Security best practices for native interop
Success Criteria
- Full API coverage of OFIQ functionality
- Cross-platform compatibility
- Performance within 5% of native calls
- Comprehensive test coverage (>90%)
- Production-ready deployment packages
- Complete documentation and samples
Future Enhancements
- Async/await support for long-running operations
- GPU acceleration integration
- Custom quality measure extensions
- Real-time video processing
- Cloud deployment optimizations